Python SDK (Local)

SpawnCodex SDK Documentation

A static, double-click documentation set for the local Python SDK wrapper around codex exec. The SDK now supports sync + async execution, live streaming, retries/backoff, and persistent named sessions.

Run Codex from Python

Use run() and run_prompt() for deterministic non-interactive tasks.

Async API

Use run_async(), resume_async(), and async live runs for asyncio workflows.

Stream Events Live

Use run_live()/run_live_async() to consume JSONL events as they arrive.

Retry Policy

Use RetryPolicy on CodexLocalClient for built-in backoff retries.

Telemetry Hooks

Use event_hook to capture structured command/retry/live/session events.

Persistent Sessions

Use JsonFileSessionStore with session names to resume across process restarts.

Schema Output

Use run_with_schema() to constrain final output with JSON Schema.

SDK Capabilities

  • Typed request/result models with thread IDs, turn status, usage, and helper properties.
  • Sync and async execution methods for run/resume/thread flows.
  • Live streaming support for both subprocess.Popen and asyncio subprocess APIs.
  • Retry/backoff policy with jitter, timeout handling, and total retry-window limits.
  • Pluggable session stores: in-memory and JSON-file persistence.
  • Session metadata records with bounded turn history and legacy-file migration.
  • Structured observability events via CodexClientEvent + event_hook.
  • Large unit test suite covering sync, live, async, retries, and session-store behavior.

Quick Start in 30 Seconds

from codex_local_sdk import CodexExecRequest, CodexLocalClient, RetryPolicy, SandboxMode

client = CodexLocalClient(
    retry_policy=RetryPolicy(max_attempts=3, initial_backoff_seconds=0.5, jitter_ratio=0.2),
)

result = client.run(
    CodexExecRequest(
        prompt="Summarize this repository in 5 bullets.",
        sandbox=SandboxMode.READ_ONLY,
    ),
    timeout_seconds=120,
)
print(result.final_message)

See full setup on the Getting Started page.

Documentation Structure

Page Purpose Best For
Getting Started Install, async setup, retries, and persistent sessions. Initial SDK onboarding.
API Reference Full class/method reference including async and stores. Implementation and integration work.
Live Runs & Threads Streaming, session continuation, and async live patterns. Automation and orchestration.
Examples Cookbook Scenario-based snippets and runnable example mapping. Copy/paste starting points.
Testing & Quality Suite layout and quality checks for new features. Contributors and maintainers.